home *** CD-ROM | disk | FTP | other *** search
/ The X-Philes (2nd Revision) / The X-Philes Number 1 (1995).iso / xphiles / psion / intro < prev    next >
Text File  |  1995-03-31  |  7KB  |  159 lines
  1. PSIONICS FILE - INTRO
  2. =====================
  3. Introduction to the Psionics files
  4. Last modified 1994-09-14
  5. ==================================
  6. Clive D.W. Feather
  7. clive@sco.com
  8.  
  9.  
  10. The "Psionics Files" is my name for my project for collating information about
  11. programming the Psion Series 3 and 3a which is not in the manuals provided
  12. with the machines.
  13.  
  14. The intended audience of the files is the Series 3/3a OPL programmer. Thus,
  15. for example, material that can only be used by assembler programmers is usually
  16. (though not always) omitted, and constants are expressed as numbers rather
  17. than symbolic names. Except where explictly stated, material applies to both
  18. systems and MS-DOS emulations of both; differences are always indicated. In
  19. addition, most material also applies to the HC and MC, but differences are not
  20. always indicated. The term "Series 3s" is used to refer to the original
  21. Series 3, whether or not it is the version with the built-in spreadsheet.
  22.  
  23.  
  24. Legalisms
  25. ---------
  26.  
  27. The first version of the files was built up from information freely available,
  28. such as the standard manuals, the source code of various games, and Usenet
  29. postings. After I first posted them, the response of Psion was surprising:
  30. David Wood arranged for me to receive a complete set of SDK manuals !
  31.  
  32. According to David: the purpose of the copyright messages in the SDK is to
  33. allow Psion to express its proprietal ownership over the material. It may be
  34. copied and distributed so long as the original derivation from the SDK is
  35. acknowledged. What might cause Psion to seek legal redress is someone claiming
  36. complete credit for something that is actually derived from the SDK, and did
  37. not point readers to the SDK as the source of more information. Psion has no
  38. interest in trying to make any profit directly from sales of the SDK. Psion
  39. simply wishes the information to reach as many people as possible, trusting
  40. that, as a result, many good third party products will be written.
  41.  
  42. In addition, and subject to the above, I retain copyright in my intellectual
  43. property in these files; that is to say, the effort in editing and arranging
  44. them, and any text I have written. These files may be distributed through
  45. normal Usenet mechanisms, may be archived at sites offering free access to
  46. contents, and may be converted to other formats (such as HTML). However, all
  47. public copying and distribution is to be of the entire set of files, and not
  48. any subset, and any versions that are not a direct copy (this includes format
  49. conversions unless done completely automatically) are to carry a prominent
  50. note indicating that they have been edited and by whom, and that errors may
  51. have resulted.
  52.  
  53. While these files have been generated in good faith, there may be errors in
  54. them, and/or they may not reflect current releases of the EPOC operating
  55. system. No warranty, express or implied, is offered by myself or Psion in
  56. these matters.
  57.  
  58. This the preceeding three paragraphs are not to be removed or materially
  59. altered by any changes.
  60.  
  61. [Phew ! If you want to do something that the above doesn't cover, please
  62. contact me. I'm quite reasonable.]
  63.  
  64. Corrections and additions are always welcome.
  65.  
  66.  
  67. Files
  68. -----
  69.  
  70. The following files exist at present:
  71.  
  72.   AGENDA.FMT   - Format of Series 3s Agenda (.AGN) files
  73.   BITMAP.FMT   - Format of Bitmap (.PIC) files
  74.   COUNTRY.FMT  - Format of Country information files
  75.   DBF.FMT      - Format and use of Data (.DBF) files
  76.   DEVICES      - Device driver interfaces
  77.   ENVVARS      - Environment variables
  78.   FILEIO       - Filing system IO interfaces
  79.   FLASH        - Format of Flash SSD cards and ROMs
  80.   FONT.FMT     - Format of Font (.FON) files
  81.   INTRO        - This file
  82.   KERNEL       - Kernel memory organisation
  83.   LOCALES      - Locale codes
  84.   MENUPROB     - Series 3s menu problem workaround
  85.   PROCESS      - Processes and their properties
  86.   RESOURCE.FMT - Format of resource files
  87.   SOUND.FMT    - Format of sound (.WVE) files
  88.   SPR.FMT      - Format of SH3 Spreadsheet (.SPR) files
  89.   SYSCALLS.n   - System calls
  90.   SYSCALLS.IDX - Alphabetic index to system calls
  91.   WORD.FMT     - Format of Word (.WRD) files
  92.  
  93. Note that DATA.FMT has been replaced by DBF.FMT.
  94.  
  95. In addition, the files LINK and WSERVER are referred to in other files, but are
  96. not yet available.
  97.  
  98.  
  99. Other notes
  100. -----------
  101.  
  102. The following terms have specific meanings:
  103.   byte       - one byte integer
  104.   word       - two byte integer
  105.   trip       - three byte integer
  106.   long       - four byte integer
  107.   real       - 8 byte floating point number
  108.   cstr       - a string, as found in C programs, ending with the first zero
  109.                byte; the contents are all non-zero bytes, the string may have
  110.                zero length (excluding the terminating byte), and there is no
  111.                limit on the length unless stated otherwise.
  112.   qstr       - a string, as found in translated OPL programs, consisting of a
  113.                count byte followed by that many bytes; the contents may include
  114.                  zero bytes, and the length is in the range 0 to 255 (excluding
  115.                the count byte).
  116.   text       - a string, whose length is expressed externally (for example, by
  117.                occupying a fixed size buffer); it may contain zero bytes, and
  118.                does not have an initial count byte.
  119.                [This definition does not apply when the "text" is explicitly
  120.                described as a cstr or qstr.]
  121.   address    - a word (two bytes), containing the address of a variable in the
  122.                same or a different address space (all address spaces are
  123.                limited to 64k). It may be obtained with the ADDR keyword.
  124.   day number - a number of days since 1900-01-01.
  125.   abstime    - a number of seconds since 0000 GMT on 1970-01-01 (the format
  126.                used by the DATETOSECS keyword).
  127.   interval   - a number of seconds since 0000 on the relevant day.
  128.  
  129. All integers are little-endian. Whether a value is signed or unsigned can
  130. normally be deduced from context.
  131.  
  132. A real number uses IEEE 64 bit format, using a little-endian layout
  133.   Bits  0 to 51: mantissa, with binary point at left and implicit leading 1
  134.   Bits 52 to 62: biased exponent (1023 = value in range 1 <= V < 2)
  135.   Bit  63      : sign (0 = positive, 1 = negative)
  136.  
  137. Data structures are always shown with each field described as a byte offset
  138. from the start of the structure. Each field is given as either a start and end
  139. offset (the field including both), or as a start offset and type. Bytes not
  140. included in any listed field have an unknown meaning. Unused bytes are shown,
  141. and should be set to zero.
  142.  
  143. Hexadecimal numbers are indicated by a $ or & prefix. These are used
  144. interchangably; they do not imply the type or number of bits of the value.
  145.  
  146. Bits within bytes are always numbered from 0 (least significant) to 7 (most).
  147. Unused bits are not described, and should be set to zero.
  148.  
  149. Many operations use cstr values. These can be converted to and from qstr (OPL
  150. string) values as follows:
  151.  
  152.   - always use "ADDR(qstr$)+1" as the address of the cstr;
  153.   - to convert a qstr to a cstr, use "qstr$ = qstr$ + CHR$(0)";
  154.   - to convert a cstr to a qstr, use
  155.     "POKEB ADDR(qstr$),CALL($B9,0,0,0,0,ADDR(qstr$)+1)
  156.  
  157. An at sign (@) is used to indicate incomplete or missing information, or
  158. text that I plan to rewrite.
  159.